Rate Calculator

Note: If the currency of received amount is not AED, please use this API to get the latest exchange rate.

API URL

• UAT : https://uat.test2pay.com/sgs/api/transfer/calculateFundout
• Production : https://api.payby.com/sgs/api/transfer/calculateFundout

Request

Http Header

Attributes

• Content-Language String

  • Language in which the response message will be used.
  • Currently, only English is supported.
  • Example value: en
  • Maximum length: 10

• Content-Type String Required

  • Media type of the request body.
  • Required for operations with a request body.
  • Format: application/<format> (e.g., application/json)
  • Example value: application/json

• sign String Required

  • Request signature using private-key cryptography.
  • Ensures the payment gateway can verify the request origin.

• Partner-Id String Required

  • Merchant ID of your account.
  • Example value: 200001200101
  • Maximum length: 12

Http Body

requestTime Timestamp Required

Request time of the order. If the request time is more than 15 minutes away from the current time, the request will be rejected. This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.

Example value: 1581493898000

bizContent Object

The attributes are:

• networkCode String Required

  The code of which transfer network is used in this payout.

  Example value: LOCAL, SWIFT

  Maximum length: 20

• fundoutCurrencyCode String Required

  In this payout, the currency of the funds received by the beneficiary account.

  Example value: USD.

  Maximum length: 20

• orderAmount Money Required

  The total monetary value of the transfer request. It usually contains the amount and the currency, for example:

  "orderAmount":{
                "amount":100,
                "currency":"AED"
            }

Request Sample

// Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "Partner-Id": "200000018128",
    "sign": "S5Wr6x9Po1SX3nm4kRJyTueUMbnmsPGMlMjc3PcoyNyP0G5BuRAwauYjTJLeto6Bu1+893zCGmj201mjrvcXP4v/uMzQxRav5PBMp9VuQ+3dOFGclQAwr8cFAKuBDHhGAAkw1iVpdC8ZZLGl/jRUv3PCiZh6VyOLnrK7ZIevB/TetQSzCmN1xDIQo8mpDYz7YY/jSzYBnD17ePvkr4qQOWNUh7FF2nd29lo9KOQl5tJVoqT/D+PVSlZeuGr+wxBYCAyGqbVXXSAGcwF1egF6ISLJ29jpHcX/LACXxF/uf5cdzbudwPB2X0wtRw9WnowY3RUq34sidoF4DIShXVFHAg=="
}

// Http Body
{
    "requestTime":1585142880000,
    "bizContent":{
        "fundoutCurrencyCode":"USD",
        "networkCode":"LOCAL",
        "orderAmount":{
            "amount":100,
            "currency":"AED"
        }
    }
}

Response

Http Header

sign String Required

When PayBy sends response, PayBy will use its own private key to sign the message, and the merchant uses PayBy 's public key to verify the signature. If the verification is passed, it proves that the response was sent by PayBy and not faked by others.

Http Body

head

Attributes

• applyStatus Enum Required

  • The result of the request. Possible values:
    • SUCCESS: Application successful.
    • FAIL: Application failed. Check the code and msg for the exact reason.
    • ERROR: Application error. Signature verification failed. Ensure the private key used for the signature and the public key uploaded on the PayBy portal are a valid key pair.

• code String Required

  • Response code.
  • Example value: 0
  • Maximum length: 10

• msg String

  • Description of the response code.
  • Maximum length: 200

• traceCode String

  • Internal code for locating the error.

body

Notice Body is returned only when applystatus = success, and code = 0. If applystatus = error or failed; or applystatus = success, code !=0 , that indicates an error. Please check errors and try again.

• fundoutInfo Object

  The attributes are:

  • orderAmount Money Required

    The total monetary value of the transfer request. It usually contains the amount and the currency (AED), for example:

    "orderAmount":{
              "amount":100,
              "currency":"AED"
            }

• fundoutAmount Money Required

  The amount of money the beneficiary will receive.

• feeAmount Money Required

  The amount of money PayBy will charge in this transaction. It is not included in the orderAmount.

• networkCode String Required

  The code of which transfer network is used in this payout.

  Example value: LOCAL, SWIFT

  Maximum length: 20

• rate BigDecimal Required

  The exchange rate from AED to the recipient's currency is calculated using the formula:

  rate = fundOutAmount / orderAmount

  in which fundOutAmount is the amount received in the target currency, and orderAmount is the original amount in AED. The result is round to two decimal places

  Example value: 1.96

Response Sample

// Http Header
{
    "sign": "Yv+C2lOQmfERdm5GF9b2V4Y98HmX/6CFyconeOW36AoPqcb7InRcP9E5GnvJLfMoCScuNP4FBdJ5tJpL0A7yPHUMfxARi05jFRSMG97JJazDbWTbRkNM1ZupmTubhUvxvRCgvJp1k0c5yrHph+F+++W5eYho92xnkNgd62BS27i0iDRGzGSmsaPpK7MFcdlvnbbnmDZZJ0LH6RhYiJLYKl+znllQx3jNfCRjV28o22FZ35Q43mZTsS4uAZWbZ/KfaqWoV3sN62Cjj8DSg3mD6GCGWSVbxLq58DUxAq+6GwJ7Gj0Dc9nMXP3gnFW7dodQ9AjL2iHnH6Zh1Pw2D5/ung=="
}

// Http Body
{
    "head":{
        "applyStatus":"SUCCESS",
        "code":"0",
        "msg":"SUCCESS",
        "traceCode":"0837"
    },
    "body":{
        "fundoutInfo":{
            "fundoutAmount":{
                "amount":27.21,
                "currency":"USD"
            },
            "networkCode":"LOCAL",
            "orderAmount":{
                "amount":100,
                "currency":"AED"
            },
            "rate":0.27210884
        }
    }
}

Response Code

Code	Message	Cause	Workaround
0	SUCCESS	Success
400	INVALID_PARAMETER	Invalid parameters	Adjust the request parameters
400	REQUESTTIME_TOO_EARLY	Request time is too far in the past	Adjust the request time
400	REQUESTTIME_TOO_LATER	Request time is too far in the future	Adjust the request time
402	RATE_LIMIT_REJECT	Too many requests in a short time	Reduce request frequency
403	UNAUTHORIZED	API not authorized	Contact PayBy
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact PayBy
500	SYSTEM_ERROR	System error	Contact PayBy and retry later
504	SERVICE_TIMEOUT	Service timeout	Retry later
601	RISK_FAIL	Risk control validation failed	Adjust the business logic
62076	FUND_OUT_ABILITY_SUPPORTED	networkCode or fundoutCurrencyCode not enabled/supported	Contact PayBy